Velocity - Velocityを使った差込み変換

Velocityテンプレートを用いてデータの変換を行います。
Velocityについての詳細はhttp://velocity.apache.org/を参照してください。

■ストリーム情報

入力	フォーマット	すべて
	接続数	無制限
	説明	複数のストリームを直接差し込むことができます。 入力したストリームは$in.arrayメソッドを使用してアクセスします。
出力	フォーマット	Text,XML,CSV,HTML

■コンポーネントプロパティ

名前	プロパティ型	マッピング	説明
テンプレートの指定方法	choice	-	Velocityテンプレートをファイルで指定するか直接入力するかを指定します。 選択された指定方法によって使用する以下のプロパティが異なります。指定方法を選択すると、プロパティの表示が切り替わります。 ファイル [File] - 外部ファイルから読み込みます。 直接入力 [Inline] - テンプレートの内容 から直接読み込みます。
テンプレートの内容	string	入力＆出力	テンプレートの指定方法 が「直接入力」の場合にVelocityテンプレートを直接入力します。
ファイルパス	remoteFile	入力＆出力	テンプレートの指定方法 が「ファイル」の場合にVelocityテンプレートのパスを指定します。 テンプレートパスには絶対パスを指定することはできません。
ファイルパスの起点	pathResolver	-	テンプレートの指定方法 が「ファイル」の場合にテンプレートファイルパスのベースフォルダーを指定します。 プロジェクトフォルダ [Relative] - プロジェクトファイルと同じフォルダーを起点にします。 ホームフォルダー [ProjectOwner] - ユーザーのホームフォルダーを起点にします。
ファイルのエンコーディング	choice	入力＆出力	テンプレートの指定方法 が「ファイル」の場合にVelocityテンプレートファイルのエンコーディングを指定します。
XPath式のプレフィックス	string	入力＆出力	XPath式の中で変数を使う場合のプレフィクスを指定します。
ローカル変数	category	入力＆出力	コンポーネント内でのみ有効な変数を定義します。 Velocityテンプレート内では$localとして参照できます。
拡張クラス	category	入力＆出力	テンプレートで使用するjavaクラスを追加します。 例えばVelocityToolsのDateToolを使用する場合には定義名に「date」、Javaクラスに「org.apache.velocity.tools.generic.DateTool」を指定すれば、Velocityテンプレート内では$dateとして参照できます。指定するクラスには引数を取らないコンストラクタが必要です。 外部ライブラリを使用する場合、そのjarファイルは[INSTALL_DIR]/flow/lib/userlibに配置してください。 (VelocityToolsを使用する場合も同じ場所にjarファイルをコピーする必要があります。)

■ループ処理

なし。

■トランザクション処理

コミット	何もしません。
ロールバック	何もしません。

■エラー処理

タイプ	パラメーター	エラー処理フロー へのストリーム	エラー コード	説明
汎用	なし	コンポーネントの入力ストリーム	なし	テンプレートファイルが見つからなかった場合 文法エラーなどテンプレート処理でエラーが発生した場合
			1	拡張クラス のJavaクラスに指定したクラスが見つからなかった場合
			2	拡張クラス のJavaクラスに指定したクラスのインスタンス化に失敗した場合

■テンプレートの編集画面

コンポーネントをダブルクリックするか、右クリックメニューの「テンプレートの編集」を実行することでテンプレートの編集画面が開きます。
この画面ではテンプレート内容やローカル変数、入力ストリーム定義などの設定をまとめて行うことができます。
また、テンプレートをあらかじめ保存してある一覧から読み込んだり、テストデータを使用してのプレビューを表示することも可能です。

「テンプレート」テキストボックス

テンプレート内容を記述します。
テンプレート内容はテンプレートの指定方法 が「直接入力」の場合は テンプレートの内容 に、「改行コード」に指定した改行コードで保存され、「ファイル」の場合は指定のファイルに、「改行コード」に指定した改行コードで保存されます。

「ローカル変数」タブ

インスペクタのローカル変数 をここでも設定することができます。

「入力ストリーム」タブ

直前に接続されているコンポーネントのストリーム定義をここでも設定することができます。
ストリーム型は変更することができません。また、直前に接続されているコンポーネントがない場合や、そのストリーム型がAnyの場合はこのタブは表示されません。

「テストデータ」タブ

プレビューで使用するテストデータを指定することができます。
入力ストリームがRecord、CSV、FixedLengthまたはParameterListの場合はテストデータはCSV形式で指定してください。XMLやTextの場合はそのままテキスト形式で指定してください。

入力ストリーム定義がない場合はこのタブは表示されません。また、テストデータの内容は保存されないため一度プロジェクトを閉じて再度開いた場合には空になります。

「一覧から読み込み」「一覧に保存」ボタン

テンプレート内容、ローカル変数、入力ストリームのフィールド定義、テストデータをセットにして名前をつけて保存しておくことができます。一度保存したデータはいつでも「一覧から読み込み」ボタンで読み込むことができます。

「プレビュー」ボタン

テンプレート内容とテストデータを使用して、結果のプレビューを表示します。プレビューファイルはクライアント環境で作成してファイルにするため、以下の制限があります。

• 外部変数セットとシステム変数は参照できません。
  プレビュー上では「$exvar.xxxx」のようにキーワードがそのまま表示されます。
• フロー変数とローカル変数は設定した初期値で表示されます。
• テンプレートで#parseなどの外部ファイルを参照する機能を使用している場合はプレビューできません。

■テンプレートで使用可能なオブジェクト

値(Value)

変数やレコードのフィールド値は値オブジェクトとなります。
値オブジェクトには以下のメソッドが実装されています。

メソッド名	引数	返り値の型	説明
strValue()	なし	String	String型としての値。
intValue()	なし	int	Integer型としての値。
longValue()	なし	long	Integer型としての値。
doubleValue()	なし	double	Double型としての値。
decimalValue()	なし	BigDecimal	Decimal型としての値。
dateValue()	なし	Date	DateTime型としての値。
booleanValue()	なし	boolean	Boolean型としての値。
byteValue()	なし	byte[]	Binary型としての値。
isNull()	なし	boolean	値がnullの場合にTrueを返します。

値オブジェクト自体はstrValue()と同じ値を返します。

変数

フローの各変数とコンポーネントで定義されたローカル変数はそれぞれ変数オブジェクトとして参照可能です。
以下のリファレンス表記で変数を参照することができます。

変数の種類	リファレンス表記
フロー変数	$flow.＜フロー変数名＞
外部変数セット	$exvar.＜外部変数セット名＞.＜変数名＞
システム変数	$system.＜システム変数名＞（英語名）
ローカル変数	$local.＜ローカル変数名＞

変数オブジェクトには以下のメソッドが実装されています。

メソッド	引数	返り値の型	説明
get()	String (変数名)	Value	変数名に対応する値が返ります。 「$flow.var1」のように変数名を直接記述する記法も有効です。

変数オブジェクト自体は変数の一覧を返します。
つまりテンプレート中に「$system」とのみ記述した場合、システム変数の一覧が出力されます。

未定義の変数を参照する場合に $flow.var1 と記述しておくと参照されずにそのまま出力されます。 この場合に参照を $!{flow.var1} と記述しておくことで変数が参照出来ない場合には $flow.var1 と出力されるかわりに空白文字列を出力することが可能です。

サンプル

フロー変数「var1」の値は「$flow.get("var1")」です。
getを省略して「$flow.var1」と記述することもできます。
#if ($flow.var2.intValue() == 1)
     フロー変数「var2」の値が1の場合だけこの文字が出力されます。
#end
#if ($exvar.exvar1.var3.strValue() == "abc")
    ifの中で文字列や数値と比較を行う場合はstrValue()やintValue()を用いて比較するオブジェクト
    の型をそろえる必要があります。
    「$exvar.exvar1.var3 == "abc"」と記述しても比較する型が異なるため、結果がtrueになること
    はありません。
#end

ストリーム配列($in)

コンポーネントに入力されたストリームはすべて$inに格納されます。
arrayメソッドを用いて各ストリームにアクセスすることができます。
このオブジェクトではCollectionとなっているのでforeachを用いて各ストリームにアクセスすることもできます。

メソッド名	引数	返り値の型	説明
array()	int	Stream	インデックスを指定して入力ストリームを取得します。
array()	String	Stream	コンポーネント名、またはリンク名を指定して入力ストリームを取得します。
size()	なし	int	配列中に含まれるストリームの数。

$in自体はすべてのストリームの情報を文字列化した値を返します。
$inは自身のメソッドではないメソッドが使用された場合、array(0)に対してフォワードします。
つまり「$in.array(0).〜」という書式と「$in.〜」は同じ意味です。

ストリーム(Stream)

入力ストリームオブジェクトです。XML以外のストリームはすべてこのオブジェクトとなります。
recordメソッドを用いてストリーム内の各レコードにアクセスすることができます。

メソッド名	引数	返り値の型	説明
records	なし	Collection	RecordにアクセスするためのCollectionを返します。
record()	int	Record	インデックスを指定してレコードを取得します。
text()	なし	String	ストリームの文字列値。
size()	なし	int	ストリーム中に含まれるレコードの数。
variable()	String	Value	ストリーム変数を返します。
variablenames()	なし	Iterator	ストリーム変数名の反復子を返します

Stream自体はtext()と同じ値を返します。
Streamは自身のメソッドではないメソッドが使用された場合、record(0)に対してフォワードします。
つまり「$in.array(0).record(0).〜」という書式と「$in.array(0).〜」は同じ意味です。
これらの省略記法は入力ストリームがParameterList 1つの場合に「$in.field1」のように書けるので便利です。

ストリーム変数を取得する場合は下のように記述します。

$in.variable("FilePath")

#set ($data = $in.array(2))
$data.variable("FilePath")

レコード(Record)

レコードオブジェクトです。
fieldメソッドを用いてレコード中の各フィールド値にアクセスすることができます。
このオブジェクトではCollectionとなっているのでforeachを用いて各フィールド値にアクセスすることもできます。

メソッド名	引数	返り値の型	説明
fields	なし	Collection	各フィールド値(Value)にアクセスするためのCollectionを返します。
field()	int	Value	インデックスを指定してフィールド値を取得します。
field()	String	Value	フィールド名を指定してフィールド値を取得します。 「field("field1")」と書く変わりに直接「field1」とする指定も可能です。
name()	int	String	インデックスを指定してフィールド名を取得します。
getNo()	なし	int	レコードの行番号(0ベース)を取得します。
size()	なし	int	レコード中に含まれるフィールド数。

Record自体は各フィールド名とフィールド値をすべて文字列化した値を返します。

サンプル

---
$in.text()
---
$in.array(0).text()
---
$in.array("FileGet1")
---
入力ストリームが「FileGet1」コンポーネント1つだけの場合は上の3つの出力はすべて同じになります。


#foreach ($data in $in)
    #foreach ($r in $data.records)
        $r.name(0) = $r.field(0)
        $r.name(1) = $r.field("Field2")
        $r.name(2) = $r.Field3
    #end
#end
---
入力ストリームが複数ある場合は上のようにすべてのストリーム、すべてのレコードにアクセスする
ことができます。
入力ストリームが１つだけであるなら「#foreach ($r in $in.records)」でもOKです。

XMLストリーム

ストリームがXMLの場合、それはXMLストリームとなります。
XMLストリームでは通常のストリームのメソッドに加えて「doc」というメソッドでXMLのDocumentに対してJDOMオブジェクトとしてアクセスすることができます。
JDOMについてはhttp://www.jdom.org/を参照してください。

メソッド名	引数	返り値の型	説明
doc	なし	org.jdom.Document	JDOMのドキュメントオブジェクト。

サンプル

$in.doc.rootElement.getChild("record").getChild("field").text
文書要素の最初の子要素「record」の最初の子要素「field」の値を表示します。


#foreach ($r in $in.doc.rootElement.getChildren("record"))
  $r.getChild("field").text
#end
record要素が複数ある場合、foreachでループを回すこともできます。


ネームスペースが使用されている場合はNamespaceを第2引数とするメソッドを使用します。
#set ($ns = $in.doc.rootElement.namespace )
#foreach ($r in $in.doc.rootElement.getChildren("record", $ns))
  $r.getChild("field", $ns).text
#end
record要素とfield要素のネームスペースが文書要素と同じであれば上のようにして値を取得できます。

XPath($xpath)

XMLストリームに対してXPathを適用するためのユーティリティクラスです。

メソッド名	引数	返り値の型	説明
createXPath()	String	XPath	XPath式を引数としてXPathオブジェクトを作成します。作成されるのはJAXENのXPathクラスです。
booleanValueOf()	String, Object	boolean	createXPath(expr).booleanValueOf(object)と同じです。
numberValueOf()	String, Object	Number	createXPath(expr).numberValueOf(object)と同じです。
selectNodes()	String, Object	List	createXPath(expr).selectNodes(object)と同じです。
selectSingleNode()	String, Object	Object	createXPath(expr).selectSingleNode(object)と同じです。
stringValueOf()	String, Object	String	createXPath(expr).stringValueOf(object)と同じです。
valueOf()	String, Object	Object	createXPath(expr).valueOf(object)と同じです。

XPath式の中での名前空間定義は入力XMLストリームの名前空間定義に従います。

XPath式の中で変数を参照する場合は「/root/field1[@name=$fv:flow.var1]」のように変数にXPath式のプレフィックスプロパティで指定したプレフィクスをつけて参照します。
「$flow.var1」のようにプレフィクスなしで使用した場合、式がXPathクラスに解釈される前にVelocityによって変換されます。

サンプル

$xpath.stringValueOf("/root/record[1]/field[1]", $in.doc)
root要素直下の最初record要素の最初のfield要素の値を取得します。

$xpath.booleanValueOf("count(/root/record)=5", $in.doc)
root要素直下のrecord要素の数が5つの場合、trueが返ります。

#foreach ($r in $xpath.selectNodes("/root/record", $in.doc))
    $r.getChild("field").text
#end
selectNodesではListが返るのでforeachで使用することができます。

$xpath.stringValueOf("/root/record[@name='$flow.var1']/field", $in.doc)
上記の「$flow.var1」はVelocityによって変換されてからXPathに渡されます。
変数をXPath内で処理したい場合は

$xpath.stringValueOf("/root/record[@name=$fv:flow.var1]/field", $in.doc)
のようにXPath式のプレフィックスプロパティで指定したPrefixを付けて指定します。
前者は変数を「''」で括っていて、後者は括っていない点に注意してください。

$xpath.stringValueOf("/ns:root/ns:record[1]/ns:field", $in.doc)
ネームスペースを使用したXPath。
NamespacePrefix「ns」は入力ストリームのフィールド定義で行われていなければなりません。

$xpath.stringValueOf("field[1]", $in.doc.rootElement.getChild("record"))
第2引数に任意のNodeを指定することによりそこをコンテキストとしたXPathを使用することができます。

#set ($expr = $xpath.createXPath("field[1]"))
#foreach ($r in $in.rootDocument.getChildren("record"))
    $expr.stringValueOf($r)
#end
createXPathで作成したXPathオブジェクトをループの中で使いまわすことができます。
ループ中の「$expr.stringValueOf($r)」は「$xpath.stringValueOf("field[1]", $r)」と同じですが、
XPathオブジェクトの作成を毎回行わない分高速です。

システム($sys)

いくつかの汎用的な関数が$sysのメソッドとして提供されます。

メソッド名	引数	返り値の型	説明
escape()	ValueまたはString	String	文字列中の「>」「<」「&」「"」をそれぞれ「&gt;」「&lt;」「&amp;」「&quot;」に変換します。
outputXML()	org.jdom.Document	String	JDOMドキュメントを文字列化します。
outputXML()	org.jdom.Document, boolean	String	JDOMドキュメントを文字列化します。第2引数はインデントの有無です。
outputXML()	org.jdom.Element	String	JDOMエレメントを文字列化します。
outputXML()	org.jdom.Element, boolean	String	JDOMエレメントを文字列化します。第2引数はインデントの有無です。
strToInt()	String	int	文字列をintに変換します。
strToDouble()	String	double	文字列をdoubleに変換します。
getCurrentDate()	なし	Date	現在の日時を返します。
formatDecimal()	Valueまたは任意の数値型, String	String	第1引数の数値を第2引数の書式で文字列化します。
formatDate()	ValueまたはDate, String	String	第1引数の日付を第2引数の書式で文字列化します。
regexpReplace()	String, String, String, boolean, boolean, boolean	String	第1引数の文字列の中から第2引数の正規表現にマッチした部分を第3引数の文字列で置換します。第4引数は英大文字小文字の区別するかどうか、第5引数はマッチする文字列をすべて置換するかどうか、第6引数は第3引数の文字列でメタ文字(REGEXPREPLACE関数を参照)を使用できるかどうかをそれぞれ指定します。第4〜6引数は省略時でき、省略時の値はtrueとなります。

以前のバージョンにあったconvertDomToStringメソッドはインデントの有無を指定できるoutputXMLメソッドに置き換えられました。
convertDomToStringメソッドも従来同様使用できますが、今後はoutputXMLを使用するようにしてください。

サンプル

$sys.escape($in.text())
入力ストリーム全体をエスケープして出力します。

$sys.outputXML($in.doc, true)
入力のXMLをインデントして出力します。

$sys.outputXML($in.doc.rootElement.getChild("record"))
入力のXMLの最初のレコード要素以下を出力します。

$sys.formatDate($sys.getCurrentDate(), "yyyy/MM/dd")
現在日時をフォーマットして出力します。

#set ($num = 50000)
$num
$sys.formatDecimal($num, $local.FORMAT.strValue())
$sys.formatDecimal($flow.Num1, $local.FORMAT.strValue())
## Velocityでは「##」がコメント行の先頭文字として定義されているため「#,##0」のような
## 書式文字列を直接テンプレートに埋め込むことはできません。
## そのような書式を使用する場合はLocal変数を使用するなどの方法を用いてください。

$sys.regexpReplace($contents, "(s?https?://[-_.!~*'()a-zA-Z0-9;/?:@&=+$,%#]+)", '<a href="$1">$1</a>')
文字列中のURLにリンクを張るように置換します。(上記URLの正規表現は簡易的なものです)

出力エンコーディング($encoding)

出力ストリームのエンコーディングを出力します。
HTMLのcharsetを指定する場合などに使用してください。

■備考

• Velocityテンプレートはキャッシュされるため、ファイルのエンコーディング を変更後有効にするには、テンプレートファイルを更新するか、FlowServiceの再起動が必要になります。
• テンプレート内で#includeや#parseを使って外部ファイルを参照するときの起点はユーザーのホームフォルダーとなります。参照元ファイルの置かれたフォルダーやプロジェクトフォルダではありませんので注意してください。